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INTRODUCTION 
Let’s talk about BASIC - specifically, ATARI(tm) BASIC. 


When the good people at ATARI designed ATARI BASIC they 
realized that they would have to make certain compromises 
between size and function. For example, long variable names 
stayed, string arrays didn’t. The final result was an extremely 
compact but amazingly powerful Basic language. Unfortunately, 
there were still many useful features that were unavailable to 
the average hobbyist. Which brings us to this disk. 


On "PAGE 6" you can expect to find many small but powerful 
utilities whose purpose it is to put some of the “luster” back 
into ATARI Basic. Actually, utility does not adequately describe 
the nature of the programs that comprise PAGE 6. When you talk 
of utilities, you tend to think of a Basic line-renumberer, or a 
variable cross reference routine. With a few exceptions, the 
routines here are better described as "service routines"; 
programs working hand-in-hand with Basic to perform some 
useful function. 


GETTING STARTED: 

You are probably anxious to boot up the disk and see what you’re 
in for, so let’s get to work. Make sure that your ATARI Basic 
cartridge is in the left cartridge slot, and with all power off, 
turn on your disk drive. When the "busy" light goes out, insert 
the PAGE 6 diskette into the drive, and turn the computer "ON". 
The screen will go dark for a moment while we load an entry 
screen for you. 


The PAGE 6 title page will be displayed soon to be replaced by a 
menu screen to allow 3 options. Incidentally, this menu is a 
demonstration of one of the utilities called TXTCOLRS. You will 
see no less than 4 different colors on a GRAPHICS @ screen. 


The Menu options are as follows: 
COPTIONJ=DOS 
CSELECTJ=PROGRAM DESCRIPTION 
CSTART] =BASIC 
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For now, press the CSELECTI key and you will see a menu with 
the PAGE 6 programs on it. Press a mumber and a brief 
description of each routine will be displayed on the screen for 
you. Your next step will be to decide which of the routines you 
wish to start with, put the games aside for a moment, and get to 
work becoming more familiar with assembly language 
programming, and have some fun while your doing it.. | 


A FEW NOTES ON THE DOCUMENTATION: 

This documentation is set up so that each routine gets its own 
section. While this does remind one of a reference manual, not an 
instruction book, it is really the best way to do it since each 
routine is basically independent from the others. Each section is 
rigidly broken down into subsections. These subsections are 
described below: 


LANGUAGE: this tells the language that the utility is written 
in, and the disk files which contain it. A “source” file holds the 
assembly-language version of a machine language program, while 
an “object" file holds the machine code version itself. 


LOADING: this describes briefly how to load the program. 


RESTRICTIONS: details the particular requirements of the 
utility. If the requirement can’t be met then the program cannot 
be used. For example, if one utility uses page 6 of RAM, then no 
other program that also uses page 6 can be used at the same 
time. | 


AT-A-GLANCE: this provides a very cursory description of the 
utility for the curious and impatient alike. 

DESCRIPTION: Here the function of the routine is described, 
along with any USR arguments. 


INSTRUCTIONS: if the program requires you to do certain things, 
in a certain order or way, then those steps will be described 
here. 
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NOTES: are just that. They may detail some possible 
modifications in the routine, some things to watch out for, or 
they further describe how it works. 


FILE-NAMING CONVENTIONS 


In the interest if avoiding confusion we have adopted a 
file-naming policy that applies to all files on the Utility 
Diskette. 


ATARI DOS normally divides the filename into two parts; an 
eight-letter title and a three-letter extender. On the Utility 
Disk, the title is the mame of the program (reasonable so far, 
right?), while the extender is used to identify the contents of 
the file. This table describes each different type of extender: 


BAS-File contains a BASIC program which should be loaded with 
the LOAD command. 


OBJ-Machine-Language file, which can be loaded from the DOS 
menu with option (LJ. 
### USE [SYSTEM RESET] TO LEAVE DOS AND ENTER BASIC. 


ASM-Assembly-Language code; for use with the 
Assembler-Editor cartridge. Use the ENTER command to load. 


ARS-Auto-run file. This file may be loaded from the DOS or 
renamed to AUTORUN.SYS so as to be loaded upor system boot. 
This is similar to an OBJ file except that it will be initialized 
upon loading. 


LST-indicates a BASIC program which must be loaded by means 
of the ENTER command (thus allowing it to be "merged" with the 
current BASIC program). 


DMO-Demo program. The workings of these files are usually 
explained in the individual program’s documentation. 
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JOYSTICK EXPANDER 
LANGUAGE: Machine Language 
SOURCE FILE: JSTICK.ASM 
OBJECT FILE: JSTICK.OBJ 


LOADING: 

Use either the "L" command from DOS to load JSTICK.OBJ or 
merge the list format file with your own program using the 
ENTER command and the JSTICK.LST file from Basic (see note 1). 


RESTRICTIONS: 
Uses page 6 and the deferred VBLANK vector. 


AT A GLANCE: 
Assigns numeric values to a joystick direction. 


DESCRIPTION: 

When this routine is rumming, instead of the normal values, 
Basic’s STICK(n) returns one of the following numbers, depending 
upon the direction of the joystick: | 


S212 
MZ 
7 =“a- 3 
re 
a S.. 4 


A simple ON... GOTO instruction can then be used to handle 
different joystick directions which reduces the programming 
effort considerably. 
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NOTES: 


Ci) The LIST format file JSTICK.LST is a set of DATA 
statements and a USR call. It occupies lines 32700-32767 and is 
invoked by a GOSUB 32700. The program loads JOYSTICK 
EXPANDER into page six and does a USR call for you, so that 
you may easily utilize its capabilities from within a BASIC 
program. 


[2] The routine will be disconnected if [SYSTEM RESET) is 
pressed. To restart it, do a X=USR(i536). If, for any reason, it 
should get disconmected some other way, be sure to press 
(SYSTEM RESET] before initializing again. 


(3) The routine converts the normal joystick position codes into 
the vaues described above by referencing them in a table. The 
following locations are given so that you may change the 
direction values. 


LOCATION 0.S. NEW STICK 
DEC HEX VALUE VALUE POSITION 


pn ——— 

1584 $638 5 4 = right/back 
1385 $431 6 2 right/forward 
1586 $632 7 3 right 

1588 $634 9? 6 left/back 
1589 $635 18 8 left/forward 
1598 $636 11 7 left 

1592 $638 13 5 back 

1593 $639 14 1 forward 

1594 $63A 15 @ center 


The values that are passed to the O0.S. may be changed to reflect 
your own applications by simply POKEing the new value into the 
location found by using the above chart. 
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C4) 
SAMPLE PROGRAM USING THIS ROUTINE 


> X=USR(1536):REM START EXPANDER 
1@ N=STICK(@):REM READ FIRST STICK VALUE 
26 ON N GOTO 30,40,50,60,70,80,90,160,118 
30 PRINT “FORWARD":GOTO 560 
49 PRINT "RIGHT/FORWARD":GOTO 500 
98 PRINT "RIGHT*:GOTO 500 


5060 seesce 
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[3] 
JOYSTICK EXPANDER FLOWCHART: 


: Initialize the counter | 
H to 3 as there are 4 |} 
: Joysticks (8-3) 


i Get the joystick value | 
i That corresponds to i: 
H counter 


i Use the value of the stick ! 
i to index into a table of |} 
H new values H 


i: Write the new value out to | 
i; the joystick shadow register | 


| Decrement the ; 
: counter i; 


/ the \. 


i Give control to the next | 
H VBI routine H 
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QUICKTYPER 


LANGUAGE: assembly 
SOURCE FILE: QUICKTYP.ASM 
OBJECT FILE: QUICKTYP.ARS 


LOADING: 
Use the DOS L command or rename to "AUTORUN.SYS" 


#* USE CSYSTEM RESET] TO ENTER BASIC #* 


RESTRICTIONS: 
Uses page 6, the deferred VBLANK vector, ard the keyboard IRQ 
vector. : 


AT A GLANCE: 
Automatically "types" certain frequently used words or BASIC 
commands 


DESCRIPTION: 

Have you ever gotten tired of typing D-O-S just to enter DOS? 
This wonderful utility will "type" for you some of those 
bothersome words or commands. The only movement needed on 
your part is to hold down both the SHIFT key and the CTRL key 
simultaneously and press any of the standard keys. Simple. 
Let’s use the above example. To enter the command "DOS" all 
you have to do is press the SHIFT-CTRL combination and the 
letter "D". QUICKTYPER will not only type "DOS", but will also 
press return for you. 


There are a total of 414 commands or instructions that are 
handled by QUICKTYPER to make your programming life a bit 
easier. The automatic [RETURN] press after some of them is 
especially helpful. 
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INSTRUCTIONS: 

Here is a list of keys and their associated QUICKTY PER text. Of 
course, all letters must be struck while holding the SHIFT and 
CTRL keys down to receive the QUICKTYPER manifestations. 
NOTE: anything enclosed in relational symbols ("<>") represents 
a special key. 


{inv) INVERSE (ATARI KEY) 
{ret> CARRIAGE RETURN 
{caps> CAPS/LOWR KEY 
{CAPS> SHIFT-CAPS/LOWR 


KEY TYPES SPECIAL NOTES 
6 PR. #6 : PRINT TO DEVICE #6 
E SET. SETCOLOR 
T LIST <ret> LIST A PROGRAM 
P PRINT 
CLEAR GR.@ {ret> | see note (1) 
UP ARROW PEEK( 
DN ARROW POKE 
0 SOUND 
§ SAVE 
D DOS <ret> ENTERS DOS 
ATARI DATA 
END TURN SOUNDS OFF 


SPACE REM {inv)<caps) see note (2) 
RETURN <ret><inv><CAPS> see note (3) 


NOTES PERTAINING TO ABOVE: : 
{) "GR." is very useful for getting out of mixed graphics display 
such as GRAPHICS 2. 
2) This is handy for highlighting comments within a program. 
These REM statements will be in INVERSE LOWERCASE, which 
not only makes them look slick, but also causes them to stand out 
from normal lines. 
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3) If you followed the advice given in note (2) above, then this 
should be used instead of a normal CRETURN). This will return 
the inverse and lowercase status to normal. 


If at any time, you would like QUICKTY PER disabled, simply hold 
down [OPTION] and press ([S/RESET]. To re-enable 
QUICKTY PER, press [S/RESET]) by itself. 


NOTES: 


C4] QUICKTYPER pulls its words out of a table. If you don’t 
mind a bit of work, you can add your own words into it. 

Each entry in the table consists of two parts; the first part 
contains the SHIFT-CTRL key value for the entry, while the 
second part contains the entry itself. For example, the entry for 
"DOS Creturn]" is: 250,$7A,$48,$7E,$0C 


The "250" is the SHIFT-CTRL code, while the hex numbers are 
what QUICKTYPER types. Note that the byte values given in the 
second part are raw keycodes; that is, they are not ATASCII or 
internal format, but are the actual keyboard codes, the same as 
those read out of the KBCODE ($D209) register. A list of 
keyboard codes appears on page III.i6 of the ATARI PCS 
HARDWARE MANUAL and page 5@ of the OPERATION SYSTEM 
USER’S MANUAL. A table of SHIFT-CTRL key manifestations is 
giver at the end of these notes. 

When modifying the table, take care not to exceed the page 6 
boundaries. If you run out of room, you can always delete some 
of the current entries. 


[2] The speed at which the letters are "typed" 1s controlled by 
the variable DELAY at location 1684 ($694), which is normally 
set to one. A delay of 255 ($FF) is approximately 4 1/2 seconds. 
Do not set the delay to zero as this will cause the program to 
produce undesirable results. 
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It is interesting to note that you can type normally between each 
"“Quicktyped" key while QUICKTYPER is typing. 
(3) TABLE OF SHIFT-CTRL KEYS 


NOTE: Not all keys have a SHIFT-CTRL representation 


KEY DEC VALUE HEX VALUE 
D 25 SFA 
E 234 SEA 
F 248 $F 
G 253 $FD 
H 249 $F9> 
I 205 CD 
M 229 $E5 
N 227 $E3 
0 200 cs 
P 202 $CA 
Q 239 SEF 
R 232 $ES 
S 254 $FE 
T 237 $ED 
U 203 $CB 
WW 238 $EE 
Y 235 $EB 
i 223 $DF 
2 222 $DE 
3 218 $DA 
4 216 Ds 
5 221 DD 
} 219 $DB 
? 243 F3 
8 245 $F5 
> 240 $FO 
Q 242 $F2 
< 246 $FS 
> 47 $F7 
BS 244 $F4 
~ 206 $CE 
= 207 CF 
, 224 SEO 
: 226 $E2 
/ 230 $ES 
RETURN 2804 CC 
SPACE 225 $E 1 
ATARI 231 $E7 
CAPS 252 $FC 
ESC 220 $DC 
TAB 236 $EC 
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C4] QUICKTYPER has been set to "load & go"; it was designed to 
run as an AUTORUN.SYS file or by loading from DOS. However, 
this does not allow the program to be disconnected from BASIC. 
If a BASIC program that is in the memory at the same time as 
this program uses page 6 at all, it must first disable 
QUICKTYPER. This is done by holding down COPTION) and 
pressing (SYSTEM RESET. 
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INFORMER 
LANGUAGE: Machine Language 
SOURCE FILE: INFORMER.SRC 
OBJECT FILE: INFORMER.OBJ 


LOADING: DOS 2.05 menu option [LJ or rename to 
AUTORUN.SYS to load when you boot DOS. 


RESTRICTIONS: Uses PAGE 6 and deferred VBLANK vector. 


AT A GLANCE: 

Provides a "window" into your ATARI that allows you to see: 
CAPS/lowrmode, cursor column and row, escape flag, pause mode 
status, and keyboard buffer filled indicator. Updated every 
1/6@th of a second. 


DESCRIPTION: 

INFORMER produces an information line that resides above the 
top line display on the TV screen. When read from left to right 
this line provides the following information: 

MODE: This indicates the current SHIFT-LOCK status. If you 
press SHIFT and CAPS/LOWR, a letter "A" is displayed, 
signifying that all input will be in uppercase letters. Similarly, 
am “a" indicates lower case, while a ‘heart’ is shown if all 
keypresses are to be interpreted as CONTROL characters (this 
occurs when you press [CTRL] + [CAPS/LOWR)). In addition the 
mode display also indicates whether all input is to be in inverse 
or normal characters. The inverse characters are as a result of 
pressing the ATARI key and when it is in effect, the MODE field 
will be displayed white on dark. 


R,C - This shows the current cursor position. In addition to the 
GRAPHICS @ cursor, the position of the invisible graphics cursor 
is displayed as well. NOTE: garbage will appear in these fields if 
the number exceeds 4@ as cam happen in GRAPHICS 7 and 8. 
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S: - This field consists of three letters which appear if a 
specific corresponding condition exists. 

"E" is displayed when ESCAPE is pressed. This indicates that the 
next screen-edit key (eg.-INSERT,DELETE) will be interpreted 
as a graphic value. 

"C" indicates that a keypress is waiting to be read by the 
Operating System. 

"S" occurs when the output is paused by means of pressing 
LOTRL J #011. 


Once invoked, INFORMER stays at the top of the screen until the 
computer is turned off, or the deferred VBLANK vector is reset. 
Should you switch screen: modes, it will reinstate itself at the 
top of the new screen display. Even pressing [SYSTEM RESET] 
will not disturb INFORMER, and since informer sits above the 
screen that ATARI uses it will not hamper program operation. 


NOTES: 

{. The INFORMER line disappears during time-critical periods 
like disk input or output. When time is not crucial it will 
reappear updated and ready to review. 

2, The actual INFORMER line replaces one of the 
BLANK-8-SCANLINES instructions in the display list. Since 
these 8 blank lines are visible on most TV's (they‘re that black 
border along the top of the screen) this arrangement causes no 
problems. However, some televisions are adjusted such that 
these lines aren’t visible, with the result that the INFORMER 
LINE doesn’t show. One solution to this is to POKE 1686($676) 
with a 112($2@), which will shift the display down by adding 7 
more blank lines at the top of the screen. 

3. You can disable informer by pressing COPTIONI+(S/RESET]J. 
To reinstate, just press (S/RESET]. 

4, This routine will not work with the ATARI Editor/Assembler 
cartridge, since the editor "squelches" all deferred VBLANKS. 

5S. INFORMER can be set up as a "load & go" file by renaming it 
to "AUTORUN.SYS". However, if a BASIC program uses Page 6 at 
all, it must first disable INFORMER by holding down COPTION] 
and pressing (SYSTEM RESET]. 


Page iz 


INFORMER II 
LANGUAGE: Machine Language 
SOURCE FILE: INFORM2.SRC 
OBJECT FILE: INFORM2.0BJ 


LOADING: DOS 2.65 meru option [LJ] or rename to 
AUTORUN.SYS to load when you boot DOS. 


RESTRICTIONS: Uses PAGE 6 and deferred VBLANK vector. 


AT-A-GLANCE: 
Almost identical to standard INFORMER, except that BASIC’s 
available memory is displayed. 


DESCRIPTION: 

INFORMER II is the same as the normal INFORMER routine 
except that the status flags (right-most fields) have been 
replaced with a "free memory" counter. This counter shows the 
number of characters of memory currently available to the ATARI 
BASIC programmer. This memory value is displayed in 
HEXIDECIMAL. 


NOTES: 

1. Free memory is calculated by subtracting the double-byte 
value of MEMLO ($90-91) from the double-byte value of HIMEM 
($2E5-2E6). It should be noted that MEMLO is maintained by 
BASIC, and is not to be confused with the Operating System 
MEMLO pointer. 


2. The POKE location given in note #2 of INFORMER is now 1715 
($6B3), to move the INFORMER line down the screen. 
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BIGPRINT I 
LANGUAGE: BASIC 
BASIC FILE: BIGPRINT.BAS 


RESTRICTIONS: 
Requires a printer. 


AT A GLANCE: 
Prints 1 1/2 inch large horizontal lettering on a printer. 


DESCRIPTION: 

Most printers contain a bewildering variety of printing styles, 
such as double-width characters, boldface, and proportional 
print. However, few will print one-inch or larger letters. It was 
with this startling deficiency in mind that BIGPRINT was 
created. 


BIGPRINT will produce { 1/2 inch high characters on a printer, 
with up to ten such characters per line. It will also print in 
inverse, and will use any redesigned character set, as well. 


INSTRUCTIONS: 

The best way to describe how to use BIGPRINT I is to go through 
a typical example. Let’s say that we want to print the following 
poster: 


BOY! Do! 
like SPAM! 


AS you can see, neither line contains more than ten characters 
(including spaces). Ten characters is all that will fit on an 
eighty-column page. 


If you have not already done so, type RUN"D:BIGPRINT.BAS" to 
to rum BIGPRINT. When BIGPRINT is started, it will ask the 
following: 
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SPECIAL PRINTER CONTROL CODES? 


This is your chance to initialize your printer. Enter any control 
codes that will set it up for your poster (perhaps invoke boldface 
type, or marrow character width). Remember, amy ESCAPE 
characters may be sent by typing ESCAPE twice. If your printer 
is fine the way it is, then press CRETURNJ. The program also 
takes this oportunity to check printer status. If the printer is 
not on, the message "TURN PRINTER ON" is displayed, and the 
program tries again. BIGPRINT will continue trying until the 
printer is made ready, break is pressed, or the 6502 processor 
melts. 


Now it’s time to enter your message. BIGPRINT displays the 
following prompt: 


ENTER YOUR MESSAGE (1@ characters max.) 

? <10 ° 

Type in the first line of the message, "BOY! Do I". The "<1" 
marker shows you where the i@th character lies. Do not go 
beyond this marker! 


You may have noticed that you are allowed to enter inverse, 
lowercase and graphic characters. Since the program only asks 
you for one line at a time, we will have to enter the next line of 
our message later (build our poster slowly). 

Now, BIGPRINT asks: 


FILL CHARACTER TO BE USED? 


BIGPRINT is asking for a character that will be used to print 
each "white" portion of a letter. You see, each ATARI [tm] 
character is made up of little dots arranged in a pattern (if you 
look closely at your TV screen you can see them). When printing 
your poster, the program will use the fill character to form each 
letter instead of a little white dot. 
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If you press CRETURN] right now without entering a fill 
character, then the program will assume that you would like the 
character fill to be composed of the individual letter itself (i.e. 
the letter "A" will be formed with many little "A"’s). Take 
special note that control character and/or inverse characters in 
the message may cause unwanted results on the printer if 
automatic letter fill is chosen, because the printer may interpret 
the characters as control codes. Some printers such as the 
EPSON MX series have graphics character that may printed. 
These are valid. 


BIGPRINT now compiles the information and prints the first line 
of the message onto the printer. When it finishes, BIGPRINT 
types: 


DO YOU WANT TO PRINT ANOTHER LINE? 

Since we now have to print the second line, type a "Y". Type in 
the second line and do everything over again, just like you did it 
with the first line, except use the second line of your message. 
When everything is done, and it is asking you if you want to print 
another line, type "N" to get out of the program. 


BIGPRINT will use whatever character set happens to be in use 
at the time it is rum, to print the poster. Thus if you have a 
futuristic type character set or any other kind for that matter 
(created by using one of the character editing type programs 
currently available on the market) it will be used as a substitute 
for the standard ATARI [tm] character set. It is important to 
note however, that the fill character will be whichever standard 
your printer happens to use, and not the redesigned version. 


Page 16 


BIGPRINT II 
LANGUAGE: BASIC 
BASIC FILE: BIGPRNT2.BAS 
RESTRICTIONS: Requires a printer. 
LOADING: RUN from BASIC 


AT A GLANCE: 
Prints banners with vertical lettering. 


DESCRIPTION: 

BIGPRINT II closely resembles its younger brother BIGPRINT, 
so before reading any further, you should go back and read that 
documentation. | 


This program prints banners with variable sized lettering. A 
banner is simply a long strip of paper that can be read when it is 
held sideways. Of course, if a modified character-set is in use 
when BIGPRINT II is run, it will be used to form the actual 
characters printed. 


INSTRUCTIONS: 

BIGPRINT II is picky about the printer being turned on and 
ready, so you should turn your printer on BEFORE you actually 
run the program. If it is not on then the message "TURN 
PRINTER ON" will be displayed...and re-displayed...and 
re-displayed...until you actually do so. 

The first intelligent sign of life from BIGPRINT II is the 
following question: 


CHARACTER WIDTH?5 

You may notice that a "5" is already typed for you to serve asa 
default answer and may be entered by just pressing C[RETURN], 
otherwise type over it with your own number. The next prompt is 
this: 
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CHARACTER LENGTH?9 

This also has a default answer ("9"). If this is OK, press 
CRETURN], otherwise, type over it as usual. 

Bear with us a moment while we explain character length and 
width to you. All characters are formed in an 8x8 grid, or matrix. 
Here is an example of the letter "H": 


a i | 
ES as 
XX 
EK 
~ X%% 


X 
¥ 
X 
o X % 
x 
RX. .k 


On the TV screen, each individual grid is very small. On the 
printer, each box within the grid is printed as a square of a 
letter (or a space). The size of the letter is determined by the 
character width and the character length. The width refers to 
the number of characters left to right per box, while the length 
refers to the number from top bottom per box. Thus, if you use 
the default values supplied, each character will be 4@ characters 
wide (5 LETTERS/BOX x 8 BOXES) and 72 letters high (9x8). Be 
sure that there is room on your paper to accomodate the length 
you choose. Continuing with the instructions, BIGPRINT II then 
asks: 


FILL CHARACTER?+# 

Again, a default is provided ("*"), The fill character is the 
character used when printing each letter. A fill character must 
be supplied (no automatic lettering like BIGPRINT). In the same 
manner, you should enter the space character in response to the 
following prompt: 


SPACE CHARACTER 

Here, the default character is a space (you can’t see it, can 
you?). Like the fill character, this character is printed for the 
appropriate parts of the character (blank boxes within the grid). 
It is now time to enter the message. BIGPRINT gives a prompt 
like this: 
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INPUT MESSAGE (10@ char max)? 

Type in your message now (up to 1@@ characters). Anything is 
valid, including inverse and control characters. When finished, 
press CRETURN) and your banner will start to be printed. 

When the banner is finished, you will be given the program’s last 


prompt: 


ANOTHER MESSAGE? | 
If you enter “Y", the program starts from the top agair, 
otherwise it terminates normally (terminate is a fancy word for 
stop). 


a 
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SLOWLIST 
LANGUAGE: Machine Language 
SOURCE FILE: SLOWLIST.SRC 
OBJECT FILE: SLOWLIST.OBJ 


LOADING: DOS 2.05 meru option [LJ or rename to 
AUTORUN.SYS to load when when you boot DOS. 


RESTRICTIONS: Uses Page 6 and deferred VRLANK vector. 


AT-A-GLANCE: 
This routine allows the BASIC programmer to pause and/or slow 
a program listing by pressing specific Console keys. 


DESCRIPTION: 

You can stop a listing om the ATARI by pressing the combination 
of [CTRL] + [i] keys. This can be a bit cumbersome, especially 
when there is a complex listing scrolling by. SLOWLIST will 
allow you the option of stopping the listing or just slowing it 
down a touch so that it cam be read as it passes. This is done 
with the [SELECT] key to slow and the [START] key to pause, 
making it a one finger operation. 


NOTES: 

C1) The routine works by checking the console buttons during the 
vertical blank interrupt. If a press is noted, the SSFLAG ($2FF) 
is set accordingly. 

[2] The listing speed can be changed by changing the contents of 
location 1619 decimal ($653). Experiment with it to find a speed 
that is comfortable. 

(3) To turn the routine off, simply hold the COPTION) button 
down and press [SYSTEM RESET]. You can reinitialize the 
routine with X=USR(i536). 
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CONSOLE 
LANGUAGE: Machine Lanquage 


SOURCE FILE: CONSOLE.SRC 
OBJECT FILE: CONSOLE.OBJ 
DATA FILE: CONSOLE.LST 


LOADING: DOS 2.05 menu option CLI or merge with BASIC usirg 
the ENTER command. 


RESTRICTIONS: 
Uses Page 6 and the deferred VBLANK vector. The LST file also 
uses BASIC lines @ and 3200@+. 


AT-A-GLANCE: 
This routine makes the 3 console keys multi-functional giving 
greater flexibility to the programmer. 


DESCRIPTION: 

The 3 yellow console keys allow the programmer to use single 
key input instructions for the user. For example, an instruction 
may read "Press [START] to begin". This routine adds to that 
capability by doing 2 things: 


{ - It takes the value of the console buttons, and OR’s in certain 
bits to tell if the CSHIFTJ key is also pressed. This expands the 
number of programmable key-press options you have. 


2 - It offers the option of having the value "latched". This 
means that if a console key is pressed, the value of the key or 
combination of keys is held until you wish to use it. This acts a 
bit like the keyboard buffer which will return a single key value 
made during 1/0. This is especially useful when your program 
asks for a console key press during a printing operation, for 
example. When the current line of print is finished, you can view 
the contents of the variable RUTTON to see which key was 
pressed. 
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To utilize these features from Basic, first load the routine from 
Next; initialize the routine with a BUTTONS = USR(i536,AEX Pi!) 
where AEXPi = the option number: 


@ - turns the routine off. BUTTON will equal the hardware 
console register. 


128 - Turns the routine on, and latches the value. BUTTON will 
contain the value of the storage location to read. 


{ - Does the same as 128 except that the values do not latch. 


The BIT values that are stored in BUTTON correspond to the 
following chart: 


BIT @ [START] 
BIT 1 CSELECT] 
BIT 2 [OPTION] 
BIT 3 [SHIFT] 


From Basic, use the followina: 
KEY = PEEK(BUTTON) 


KEY corresponds to the following: 


1 [START] pressed 
2 [SELECT] pressed 
« [OPTION] pressed 


If KEY is greater than 8, then (SHIFT) is pressed also. Subtract 
8 from KEY to find out which console button is pressed. 


The source file is well documented to help you understand 
CONSOLE better, but it is suggested that you also read the 
addendum on INTERRUPTS to get a full understanding. 
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PROGRAM NAME: UTIL 
LANGUAGE: BASIC/Machine Language 
BASIC FILE: UTIL.LST 


LOADING: 
ENTER "D:UTIL.LST" from BASIC cartridge. 


RESTRICTIONS: 
Uses BASIC linenumber 1, and the variable UTIL$. Also used are 
zero-page locations 203 to 205 ($CB to $CD). 


AT A GLANCE: 
Allows BASIC users to perform some machine language 
operations upon one byte values 


DESCRIPTION: 

This utility is aimed at advanced BASIC programmers who have 
found themselves needing to AND (or, for that matter, OR) two 
bytes together, but have lacked the means to do so. UTIL can be 
used to build and execute tiny machine language programs which 
can take advantage of the 6502 processor’s power. 


It is invoked from BASIC by the USR function. The format for 
the USR statement is: 


X=USR(ADR(UTIL$),OPCODE,A,;B) 


The utility is stored in the variable UTIL$ (which is 27 bytes 
long). It is fully relocatable, and uses page-zero locations 203 
through 205 ($CE-$CD). The mumber in the first argument 
(OPCODE) determines the operation that will be performed by 
UTIL. For example, if you wanted to "AND" two numbers, the 
opcode would be 41, which corresponds to the "AND 
ZERO-PAGE-ADDR" 6502 instruction. A list of useful opcodes 
appears in note #4. 
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A and B are the two values which will be operated on, and must 
both be between ® and 255. Continuing with the previous 
example, here is the sample USR statement to AND the two 
numbers 6 and 3 together: 2 = USR(ADR(UTIL$),41,6,3) 


When UTIL finishes, Z will contain a 2, which is the correct 
result (B'0110’ CAND) B’@011’ = B’6010%. 

In most cases, A and B can be given in any order. It is important 
that no more arguments be in the USR statement, as this will 
usually cause BASIC to lock up. 

Z, in the past examples, receives the result of the instruction. 


NOTES 
{. UTIL builds the following program at locations $CB to $CD: 


$CB: opa 
RTS 


Where "op" is the instruction provided in the first argument of 
the USR statement, and "a" is the second (low byte only). The 
third argument (B) is loaded into the A; X, and Y registers before | 
UTIL JSR’s to $CB. This means that the instruction you give 
may operate on any of these three registers. The value in the 
6502’s accumulator will be returned to the BASIC program as a 
result of the USR call. 


2. UTIL assumes that the OPCODE supplied by you is a 
"zero-page address" instruction, that is, it uses a one-byte 
operand field. However, some instructions use the “implied” or 
"accumulator" addressing mode, and therefore do not require any 
operand field. When such instructions are used it is important 
that a 234 be given as the A argument in the USR statement. 
This will cause the generated program to look like this: 


$CB: op 
NOP 
RTS 
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(yes - 234 is the opcode for a No-OPeration) This works because 
UTIL stores the A argument in the second location. If the 
instruction you give does not require this location, then the 6502 
will try to interpret the value there as the next instruction. 
Putting a NOP in there pacifies the computer, and ensures that 
UTIL works correctly. 


3. The source form of UTIL is as follows: 


INDEX INSTRUCTION MNEMONICS 








i $48 PLA sTGNORE # ARGS 

2 $68 PLA sIGNORE HI BYTE OF OPCODE 

3 $48 PLA sGET LO BYTE OF OPCODE 

4-5 $8508 STA $CB -;START BUILDING INTRUCTION 

$68 PLA sIGNORE HI BYTE OF A-OP 

7 $69 PLA sGET LO BYTE A-OP 

8-9 $85C9 STA $C9 PLACE OPERAND FIELD 
10-11 $0960 LDA #$6@ ;GENERATE RTS 

12-13  $85CA STA $CA 

14 $48 PLA sIGNORE HI BYTE B-OP 

15 $48 PLA sGET LO BYTE B-OP 

16 $A TAX sCOPY INTO X, 

17 $08 TAY s AND Y REG 


18-28 $2@CB@@ JSR $@@CB ;D0 OPERATION (RESULT IN A) 
ST eSTORE RESULT FOR FUNC. 
23-24 $a9ee LOA #@ — sCLEAR EXCESS GARBAGE 
25-26 $8505 STA $05; _IN FUNCTIONAL-RETURN FIELD 
$40 RTS sBACK TO BASIC 


: 
: 
: 


INDEX is the subscript value of that instruction in the string 
array UTILS. 


Notice that the routine is fully relocatable, and that no attempt 
is made to save and restore locations $CB to $CD. 


4. This table contains some useful opcodes and the arguments 
they require. An argument listed as * should be 234 (a NOP 
instruction). 
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(OPCODE: A: B i DESCRIPTION 

‘ comes | ges! cee | eee eeseeeeressressseresss sss 
(| 41 it aibi ANDawithb 

: ¥Y taibit Mawithb 

i 74 i %i bi shift b one bit right 

; 10 ii bi shift b one bit left 

+ 106 + i bi rotate b one bit right (1) 

i 42 | i bi rotate b one bit left : 

: 128 | ¥: i disable Interrupt ReQuests [IRQs] (useful 
i; ¢ ¢ for disabling BREAK Key) (2). 

i 8 +: Xi kit re-enable IRQs. 

i 177 i ai bi generate a LDA (a) ,b (3) 

: 161 | ait bt generate a LDA (a,b) 

: 1998 | ai %i decrement location "a® by one 

; 238 i ai ¥i increment location “a° by one 


(1) Bits that "overflow" the byte are placed in the carry bit of 
the processor status register. Since the A argument is unused, 
it is possible to place a second shift instruction in it to move the 
bit into the other end of the byte. For example, 
X=USR(ADR(UTIL$),106,106,12&) generates 


ROR ;shift high bit into carry 
ROR ;now shift into low bit 
RTS 


(2) Actually, the BREAK key is not disabled, but delayed; the 
break occurs when the IRQs are re-enabled. Also, no keystrokes 
can be entered when IRQs are disabled. 


(3) LDA (a),b is, in fact, indexed indirect, while LDA (a,b) is 
indirect indexed. These come in handy when using one of the 
0.S.’s zero-page pointers. 

It isn’t practical to use the STA version of this, since the value 
to be stored -- which is passed in the B arg -- is also the index 
value. 


S. When modifying the string, be careful to use the ATASCI], and 
not the internal form, of the data. 
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MINI-DOS 
LANGUAGE: BASIC 
BASIC FILE: MINIDOS.LST 


LOADING: 
Use the BASIC ENTER command to load it in. 


RESTRICTIONS: 
Uses line numbers 32700-32727 and the following variables: COM 
and ZZ$ 


AT A GLANCE: 
Invoked by a GOTO 32700 or a GOSUB 32700, this routine is used 
as an alternative to calling the standard ATARI DOS. It 
performs some of the more useful disk commands. 


DESCRIPTION: 

This subroutine sits at the farthest extremes of BASIC awaiting 
your call. At the present time the program is set up to be 
invoked while editing/debugging, but can easily be modified to 
use from one of your programs. 


INSTRUCTIONS: . 
Start the routine with a GOTO 32700 in immediate mode. A menu 
and a prompt will be displayed, like this: 


1) DIRECTORY 
2) RENAME FILE 
3) DELETE FILE 
4) LOCK FILE 
5) UNLOCK FILE 
6) FORMAT DISK 
7) EXIT TO DOS 
8) RETURN 
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COMMAND: 

You may now select one of the eight choices by pressing the 
appropriate key on the keyboard. 

Following, is a brief description of the eight available commands: 


DIRECTORY: 

This choice will provide a full or partial list of the files on a 
specified diskette. You will be prompted and asked to enter the 
search specifications. The format is: 


D 2:%.% 

i\/ 

a 3 

| SEARCH SPECIFICATIONS 
DRIVE NUMBER (1-4) 
MANDATORY DEVICE NAME 


The example above will list all of the files on the disk in drive 
two. The default specification that is supplied will list all the 
files on the disk in drive one, but if you would like to enter your 
own search specification, simply type over the existing one and 
press the CRETURN] 

The search specifications are the same as those mentioned in the 
DOS manual, and all options are supported. But, unlike ATARI 
DOS, you must supply a device name and drive number (i.e. "D1i:", 
"D2:", etc.). 


EXAMPLES: 


D2:*.SRC 
Will list all the files on the disk in drive two with a "SRC" 
extender. 


Di:TEST.+# 
Will list all the files on the disk in drive one with "TEST" as a 
filename 
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2) RENAME FILE 

This command will allow you to change the mame of one or more 
files on the disk in the specified drive. When prompted, enter 
the device mame and drive mumber, the file to be renamed 
followed by a comma, and the new file name. Wildcards in the 
file mames are valid. 


D2:PROG.BAS,D2:PROGRAM.ZAP 
The file “PROG.BAS" in drive two will be renamed to 
"PROGRAM.ZAP". 


D:#.BAS,D:*.LST 
All files with a "BAS" extender on the disk in drive one will have 
their extenders changed to "LST". 


3) DELETE FILE 

This command will delete a specified file on the disk. Not only 
will the mame be removed from the directory, but the file itself 
will be deleted. All wildcarding in the file mame is valid. If you 
attempt to delete a locked file, an ERROR-167 will result. To 
delete the file, it must first be unlocked by using command 5 or 
the ATARI DOS equivalent. As a precaution, a delete verify 
prompt will be provided as a means of "bailing out", and should 
be answered by typing a "Y" (yes) or a "N" (no). 


EXAMPLES: 


D2:ATARI.COM 
Will delete the file "ATARI.COM from the disk in drive two. 


D2:PRO+#.BAS 
Will delete all files on the disk in drive one with the first three 
letters "PRO" and with an extender of "BAS". 


4) LOCK FILE 

This selection is used to "write-protect" a single file on a 
diskette. A locked file cannot be written to, renamed, appended, 
or deleted. Am ERROR-167 will result from trying to do one of 
the above to such a file. You may use all valid wildcards to lock 
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several files at one time. Don’t forget the device name and 
number ("Di:", "D2:", etc.) A locked file is designated by an 
- asterisk preceding it in the disk directory. Also, no error will be 
generated from trying to lock an already locked file. 


EXAMPLES: 


Di:HI.MOM 
Will lock the file in the drive with the name "HI.MOM". 


D2:*.# 
Will lock all files on the disk in drive two. 


2) UNLOCK FILE 

This command does the exact oppositte of command 4. It unlocks 
a previously locked file or files as specified by the search 
criteria. No error will result from attempting to unlock an 
already unlocked file. 


6) FORMAT DISK ; 

Formatting a diskette is the process of writing a digital pattern 
onto a diskette so that it may be read by the ATARI disk drive. 
The disk to be formatted may be blank or have unnecessary 
information on it. You will be asked to enter the drive number 
(1-4), then you will be supplied with a format verify prompt. 
Answer this prompt with a "Y" (yes) to continue or with a "N" 
(no) to abort the formatting process. 


WARNING: Formatting a diskette always destroys all files 
existing on the disk. 


ERROR NOTE: If the format fails, you will receive an 
ERROR-173. Suggested procedure is toretry the format and if it 
fails three or more times, the diskette should be discarded, as it 
has bad sectors on it. 


7) EXIT TO DOS 
This command simply invokes the standard ATARI Disk Operating 
System. 
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WARNING: If "MEM.SAV" does not exist on the diskette in drive 
one, the program in RAM will be destroyed. 


8) RETURN 

This selection returms the user to BASIC, or if MINI-DOS has 
been modified and called from a main-line program, the calling 
program will get program control (see note 1). 


NOTES ON ERRORS: 


ERROR-130 Non-existent device specified. DOS is not loaded in, 
or you forgot to include the device name and number ("Di1:", 
"D2:", etc.). 


ERROR-138 Device doesn’t respond. Make sure the drive is on 
and all connections are making good contact. 


ERROR-140 Serial bus input framing error. May be misadjusted 
drive timing. 


ERROR-144 You tried to write to a disk with a write-protect tab 
or could be disk drive timing. 


ERROR-146 Function not implemented. Make sure you have a 
DOS (FMS) that is fully compatible with ATARI DOS 2. Also, you 
may have mistyped the device name ("Di:", "D2:", etc.). 


ERROR-16@ Drive number error. The drive number you supplied 
is not compatible with the FMS loaded in. The DOS supplied on 
the disk is set for a maximum of two drives. If you have more, 
then poke location 1802 with the correct number according to the 
number of drives you have attached. 


DRIVES ALLOCATED POKE 1882 WITH 
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Go into DOS and use the "H" command to write a new DOS out to 
to the diskette. Then, reboot the system. 


ERROR-167 File locked. This error is caused by trying to delete, 
rename, append, or write to a locked file. 


ERROR-17@ The file concerned was not found in the disk 
directory by DOS. : 


NOTES 


Ci) To utilize MINI-DOS within one of your own BASIC programs 
you must do the following: 


A) Remove the "CLR:DIM 22Z$(4@)" from the end of line 32700 

B) Change the "END" instruction at line 32726 to a "RETURN". 

C) Command 7 may cause problems with some programs because if 
the file MEM.SAV does not exist on the diskette in drive one, 
DOS will erase the program im memory. And, even if MEM.SAV 
does exist, the calling program will not receive control upon 
DOS’s return. If your program is not affected by DOS being 
called, then skip ahead to step D. Otherwise, make the following 
changes to MINI-DOS. 

32703 ?"6) FORMAT DISK":? "7) RETURN" 

32706 GET #1,COM: IF COM<49 OR COM>55 THEN 32706 


32707 ON COM-48 GOTO 32708,32712,32714 
132718,32720,32722,32726 


And, remove line 32725. 


D) LIST the program to a disk by typing LIST "D:MINIDOS2.LST". 
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E) Load in your mainline program and make sure it does not use 
lines 32700 through 32727. Somewhere within the initialization 
part of your program, you must dimension 22% to 40 characters 
(DIM 722$(40)"), Ther, wherever you want MINI-DOS invoked 
place a GOSUB 32700. When the user chooses the RETURN 
option, program execution will be restored to the calling 
program. 


F) Merge the the two programs by typing ENTER 
"D:MINIDOS2.LST". Now, save the final working version out. 


(2) MINI-DOS has its own error trapping routine. If you would 
like your own used, simply change or remove the TRAP 
instruction at line 32700. 


C3] MINI-DOS, for the most part, uses X10 commands to perform 
its functions. The only exception to this is the directory listing. 
Listed below are the commands used. 





X10 COMMAND 4 FUNCTION 
32 RENAME 
33 DELETE 
33 LOCK 

36 UNLOCK 


294 ; FORMAT 
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MUSICIAN 
LANGUAGE: Machine Language 
SOURCE FILE: MUSICIAN 
LOAD FILE: MUSICIAN.LST 


RESTRICTION: uses sound register @ and the real time clock 
(locations 18,19,26). 


AT A GLANCE: Plays musical notes that you provide it. 


DESCRIPTION: 

Musician was designed with the game programmer in mind. You 
often want to play a musical jingle at some point in your game, 
such as "high score" or when a "bonus" is reached. While the 
ATARI has excellent sound capabilities, it is a long and tiresome 
task to translate actual musical notes into decimal numbers. This 
is where MUSICIAN comes in. All you have to do is give ita 
string containing the actual notes to be played. 


For example, to play the notes C,D,E,F,G,A,B, in that order you 
would pass MUSICIAN the following string: "CDEFGAB". It does 
the rest. 


The format for the USR statement is as follows: 
X=USR(ADR(MUSIC$), ADRISTRINGS$), ADRINTS$),ADR(TIME$), VOLUME) 


MUSIC$ is the variable that contains the MUSICIAN routine, and 
is 159 characters long. NT$ contains the decimal values for all 
the notes, and TIME$ holds the different tone durations. Since 
they are supplied with the utility you need not concern yourself 
with these three variables. 

VOLUME contains the volume at which the notes are to be 
played. It is exactly the same as the fourth number of a SOUND 
statement, and must be between @ and 15. 
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Last but certainly not least, is the variable STRING$, which 
contains the actual notes to be played. This string is made up of 
different elements which are described below. 


A through G: 

these are musical motes exactly as they are om a standard 
musical scale. Sharps are denoted by a following "#" (A-sharp is, 
for instance, "A#"), flats by a following "-" (A-flat is "A-"). 


Ox: 
this determines which octave will be used, "x" being a number 
between 3 and 6. "03" corresponds to the middle octave. 


Tx: 

"x" indicates which tempo the notes are to be played in. Actually, 
"x" is not the tempo itself, but a mumber that determines 
which prestored tempo should be used. As it is supplied on the 
PAGE 6 disk, MUSICIAN "knows" three tempos (1-3). 


Lx: 

this determines how long the following notes will last. "x" is a 
number between 1 and 4. The following table shows the actual 
durations based on both "x" and the current tempo: 


3 ape © See © ee 
T! 4 8 16: 
T2 2 1 a M4 
T3 (15 38 68 128 | 


(expressed in 6@ths second) 


"\" The comma is used to put a gap im your music; it causes 
MUSICIAN to wait for the shortest time allowable in this tempo 
(i.e.-a silence of Li). 


"" The period ends MUSICIAN, transferring contro] back to 
Basic. If you forget the period it will play your tune until the 
lights go out. Or, you can press (SYSTEM RESETJ 


Page 35 


MUSICIAN ignores any characters appearing in the string that 
are not described above. Not only that, it also assumes that all 
of your numbers are within given limits; if you double-cross it, 
MUSICIAN will very happily spew out garbage. Therefore, the 
only real way you can tell if you’ve made a mistake is if you 
suddenly hear "sour" motes; ones that aren’t supposed to be 
there. 


""" The semi-colon causes MUSICIAN to pause for one-twelth of 
a second. This delay is just long enough to separate each note 
from others around it (similar to releasing the key on a piano). 


NOTES: 


1. STRING ORGANIZATION: Two strings are used to supply 
information to MUSICIAN. The first one is called NT$, for 
"mote". Im it are all the actual sound frequency mumbers 
corresponding to the musical notes. Actually, each note has two 
numbers in here; one for the “pure” note, and one for the flat 
note (sharps are the flat of the next higher note). Each number 
is encoded in its ATASCII counter-part, and is in the following 
order: 

A(@3),A(04),A(05),A(06),A-(03),A-(04),A-(85),A-(06),..etC. 

There is no G sharp; MUSICIAN "wraps around" to A flat. For 
those of you who love long equations, here is one to compute the 
index into NT$, based on the note: | 


note=numerical value of the note (A=0,B=1,..etc.) 
=+3 if the note is a sharp 

+1 if the note is a flat 

inde x=(note#2+m)#4+octave-3 


The second variable is TIME$, which contains the actual length 
of each tone, based on the current tempo (Tx) and duration (Lx). 
Like NT$, it is also encoded in ATASCII, and each delay is 
expressed in 1/é6@ths of a second. The organization of TIME$ is 
as follows: 


n(TxLy)=delay in tempo x; duration#y 
n(Ti Ld) n(T1L2),...m(TiL4) n(T2L1),etc. 
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The table can be up to 36 bytes (characters or delay values) long, 
which gives a maximum of nine tempos. Three are supplied with 
the disk, and are described in the L command earlier. The 
equation used to access this table is quite simple: 
index=(tempo-1)#4+duration # 


2. MUSICIAN uses ATARI’s real time clock at locations 18-20 
($12-$14) to time each note. When the value in location 20 ($14) 
reaches the mumber indexed in TIME$ (see previous note), the 
note ends and the sound is turned off. As location 2@ is zeroed 
beforehand, this effectively destroys the accuracy of this clock. 
Therefore, do not use MUSICIAN if you are using the clock to 
time something. 


3. Several zero-page locations are used to temporarily hold 
information. The affected locations are Dé through DF, but as 
these are situated in the middle of two floating-point registers 
this should not cause too many problems (unless, of course, you 
call for music from within a numeric expression). 
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TEXTUAL DISPLAY ENHANCER 
LANGUAGE: BASIC 
FILE: TXTCOLRS.LST 


LOADING: i: 
Use the BASIC ENTER command to merge the program with one of 
your’s. See MERGING INSTRUCTIONS for important 
information. 


RESTRICTIONS: 
Uses line numbers @ and 30000+. It also uses the string variable 
ZZ$ 


AT-A-GLANCE: 
Allows one to get up to four different colors on a 
GRAPHICS-ZERO text screen. 


DESCRIPTION: 

TEX T-COLORS is basically (excuse the pun) a subroutine divided 
into two parts. The first part, if called, will allow one to get 
two colors (red and blue) on the standard text screen. The screen 
acts as a normal GRAPHICS-ZERO display except for the fact 
that upper-case is red and lower case is blue. The second part is 
for the more adventurous user. It allows two new colors, 
somewhat independent of the others to be placed on selected 
lines. Note that the two different parts cannot be mixed on the 
same line. Henceforth, we will refer to these as "modified 
lines". 


INSTRUCTIONS: 

At line zero, three things are done: (1) The string variable 2Z2$ is 
dimensionded, (2) the variable DEL is set to one in order to tell 
the subroutine to delete itself, and (3) a GOSUB 3000@ is issued 
to instate a redesigned character set that allows for the red and 
blue characters. It is necessary to note that it is not imperative 
that all of these except the DIMension statement appear on this 
line. 
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There are times when two colors aren’t enough. This is where 
modified lines come in. To modify a group of lines, set the 
variable LINE1{ to the starting line and set the variable LINE2 to 
the ending line. Then do a GOSUB 30300. The lines between 
LINE{ and LINE2 inclusive will become modified. Theses lines 
act the same as normal lines except for one catch: Some control 
characters and numbers will not appear normal when printed to 
modified lines. Because of this deficiency, it is recommended 
that modified lines be used for titles or headings. 


MERGING INSTRUCTIONS: 


4) Load your original file into memory and make sure it does not 
use the line numbers mentioned in the RESTRICTIONS section. 

2) Make any changes that you may want, as mentioned briefly in 
the description section. DO NOT RUN THE PROGRAM AT THIS 
POINT! 


CAUTION: You must follow the next step or the program will not 
function properly! 


3) LIST the program out to a disk. Type "NEW CRETURN1", and 
enter the program back into memory. This resets the variable 
table which is crucial to the program’s operation. 

4) The program may now be SAVEd or RUN as you would any other 
program. 


NOTES: 


Ci) If a GRAPHICS statement is issued anywhere in the program 
while the redesigned character set is in use, the character base 
address will be reset. When going to other graphics modes and 
text modes this has no effect, but upon returning to a 
GRAPHICS-ZERDO screen, a "POKE 756,ADDR:SETCOLOR 2,0,0" is 
needed to reset the character set to its normal status. Of 
course, the modified lines are lost when changing graphics 
modes. 
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(2] Although the colors that are initialized are satisfactory, one 
might wart to get enhanced effects by modifying them. Below is 
each SETCOLOR register and what it affects. 


C3) During debugging sessions with a program that uses 
TEXT-COLORS, it may be helpful to make the variable DEL equal 
to zero, to prevent deletion of the character set initialization. 
Then when the program is ready, reset DEL to one. 
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A BRIEF DISCUSSION OF INTERRUPTS 


Throughout this manual you’ve seen some very cryptic phrases, 
like "Deferred VBLANK" and "Keyboard IRQ", and you've 
probably said to yourself, "Huh? What’re these people talking 
about?!" (if you haven’t said this then you probably know what 
we are Saying, so you don’t need to read this). The purpose of 
this section is to shed some light on the subject of VBLANKS and 
IRQ’s. 


Before you can get a firm grip on these things, however, you 
must be familiar with the concept of interrupts. Interrupts 
provide a means of coordinatingg the computer with the outside 
world (i.e. disks, printers, modems and other devices). Probably 
the best way to explain them is with a small analogy. Pretend 
that your computer is the manager of a small hotel. Since it is a 
small establishment, he cannot afford a lot of expensive help (he 
does have several loyal servants, though, called ANTIC, POKEY, 
and CTIA), so he must perform most of the work alone. In 
addition to balancing the books he must also keep an eye on the 
front counter, in case any customer needing attention comes in. 
To help him do this he has installed a little bell with a sign that 
reads, "RING BELL FOR SERVICE." Upon hearing the bell he 
immediately stops what he is doing and rushes out to help the 
customer. When finished, he goes back to what he was doing as 
if nothing had happened. Of course, there are times when what 
he is doing is too important to just drop, so he makes a note to 
go help the customer as soon as he is finished. 


An interrupt is similar to ringing the bell; it causes the computer 
to stop whatever it is currently doing and go do something else. 
The fancy buzzword used to describe this process is “interrupt 
servicing". 


The ATARI [tm] computer distinguishes between two types of 
interrupts: suppressable and non-supressable. A suppressable 
interrupt can be ignored for awhile if the computer is too busy to 
do something about it, while a non-suppressable interrupt must 
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be taken care of immediately. Such interrupts are called NMI’s 
(Non-Maskable Interrupts), while the suppressable ones are 
called IRQ’s (Interrupt ReQuests), 


There is one type of NMI that occurs sixty times each second, 
which is called Vertical Blank Interrupt, or VBLANK. The 
computer uses it to do a lot of things, like keeping track of the 
time of day, or doing the keyboard auto-repeating. VBLANK is 
actually divided up into two parts: critical, and non-critical. The 
critical part is dome no matter what else is going on in the 
computer, while the non-critical part is passed over during "time 
critical periods" (i.e. disk I/O). The official names for these two 
parts are "Immediate VELANK" and "Deferred VBLANK", 
respectively. The addresses of the two programs that handle 
these parts are kept in "vectors" (don’t ask me who made that 
name up). 


If a program were to change these vectors so that they would 
contain the locations of some other routine, then that routine 
would be executed instead of the normal VBLANK routines. This 
is what programs like INFORMER do, so that they may constantly 
sample the computer’s status (yes, INFORMER’s information is 
being updated every 1/6@th of a second). 


There is also one more type of interrupt that should be 
discussed. It is called the keyboard IRQ (remember what an IRQ 
is?), and works like this: Whenever a key on the keyboard is 
pressed, the computer gets a suppressable interrupt (IRQ), stops 
what it is doing, and saves the code for the key in a safe place. 
For example, if you were to press the "A" key, the computer 
would would "see" the interrupt, amd promptly save the code for 
the letter "A" in some place where it won’t be touched. Later, 
this letter will "read" by BASIC (though, all of this happens too 
quickly for you to be aware of). Like VBLANK, this interrupt 
also has a vector associated with it which contains the location 
of the program which saves the key-code. QUICKTYPER 
circumvents theis program, using its own one instead. 
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If you‘re still confused after all this, don’t be upset; these are 
very advanced concepts, and a full understanding of them is NOT 
needed to use the utilities. Should you be interested in learning 
more about interrupts in general, I car: recommend chapter six of 
the ATARI Operating System User’s Manual. For a more in depth 
discussion of Vertical Blank Interrupts, read on. 


VERTICAL BLANK INTERRUPTS-technical notes 


In order to prevent the television picture from fading out, the 
ATARI video hardware must update or refresh the screen 60 
times per second. The time between when the screen display is 
finished and the new screen is started, is called vertical blank. 
As a point of information, the vertical blank lasts about 1400 
microseconds. 


At the start of the vertical blamk period, the ANTIC chip 
interrupts the 6502. The 6502 responds to this NMI 
(non-maskable interupt) by jumping to the operating systems NMI 
service routine, which determines the source of the interrupt. 
Since it a vertical blank interrupt, the 6502 jumps through the 
immediate vertical blank vector (VVBLK1) at $0222. This vector 
usually contains the address of the operating systems vertical 
blank routine (SYSVBV-$E45F). The OS’s routine takes this 
opportunity to update the hardware registers from the shadow 
registers (i.e.-colors). The OS routine ends by vectoring through 
deferred vertical blank vector (VVBLKD) at $0224. This vector 
usually points to a simple VBLANK exiting routine called 
XITVEBV ($E462). These two vectors (VVBLK1 and VVBLKD) were 
placed in RAM to allow the user to harness and benefit from this 
60HZ interrupt. 


The first step in setting up a VBI routine is to select immediate 
or deferred. In most cases it makes little or no difference which 
one is chosen, but as always there are exceptions. 


The first case arises when your routine reads or writes to 
registers which are shadowed by the operating system. For 
example, the JOYSTICK EXPANDER must change the Operating 
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System’s values AFTER they have been down loaded from the 
hardware registers during immediate VRLANK so as to have the 
last word so to speak. This is accomplished by placing JOYSTICK 
EXPANDER in deferred VRBLANK. 


The second case is when your VBLANK routine consumes so much 
time that the Operating System’s VBI routine is delayed beyond 
the end of the Vertical Blank period. This may cause some 
graphics registers to be changed while the electron beam is 
tracing. This in turn may cause unsightly results. To solve this 
your routine should be placed in Deferred VRBLANK. Your limit in 
immediate VBLANK is about 300@ machine cycles. 


The third case arises when your own VBI routine must be mixed 
with time critical I/O such as disk or cassette access. As 
mentioned elsewhere in this marual, the Operating System’s 
Vertical Blank routine has two stages - critical and non-critical. 
During critical 1/0, the Operating System VBI is cut short and 
aborts after the bare essentials are completed. You may have 
noticed that INFORMER disappears during disk I/O and now you 
know the reason! If you do not wish your own VBI routine to be 
bypassed during time critical periods, you must process your 
routine in immediate VBLANK. Take note, though, that any 
delays you create may interfere with time critical 1/0. 


A VBLANK routine usually terminates by linking to the standard 
VBI processing routine that your routine replaced. End an 
immediate VBI routine with a jump to SYSVBV ($E45F) and end a 
deferred VBI routine with a jump to XITVBV ($E4é62). Of course ,; 
you may override the Operating System’s VBLANK routine and 
have your immediate VBI routine jump directly to the XITVBV. 


To avoid vector changing problems, the Operating System 
provides a routine called SETVBV at location $E45C. To utilize 
it, load the 6502’s X register with the high byte of the address 
of your VBLANK routine, the Y-register with the low byte, and 
the Accumulator with a 6 for immediate VBI or a 7 for deferred 
VBI. Then do a JSR SETVBV and the routine will be safely 
enabled. Execution will begin within a 6@th of a second. 
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As you can see from our programs, a wide variety of operations 
can be performed during VBLANK. Some of the VBLANK routines 
utilized here incorporate very advanced concepts that would take 
volumes to explain. Therefore, we have taken extra pains to 
document the source code of the assembly routines to the fullest. 
We invite you to look over and study the source codes for the 
routines and learn something new. If you wish to print the source 
listings to the screen or to your printer, follow these simple 
steps: 


{-Go to DOS from the entry screen of PAGE 6. 

2-press (CJ for COPY 

3-type the file mame followed by a comma then the device to 
print to (E: or S: for the screen, P: for the printer). 


You will find that a little careful study of the techniques used in 
these routines will add to your understanding of Assembly 
Language programming. 





Warranty 


SYNAPSE SOFTWARE warrants to the original consumer/purchaser that this 
SYNAPSE SOFTWARE program cassette/diskette (not including the computer 
programs) shall be free from any defects in material or workmanship for a period of 
90 days from the date of purchase. If a defect is discovered during this 90 day 
warranty period, and you have timely validated this warranty, SYNAPSE 
SOFTWARE will repair or replace the cassette/diskette at SYNAPSE SOFTWARE'S 
option, provided the cassette/diskette and proof of purchase is delivered or mailed. 
postage prepaid, to SYNAPSE SOFTWARE. 


This warranty shall not apply if the cassette/diskette (1) has been misused or shows 
signs of excessive wear, (2) has been damaged by playback equipment. or (3) ifthe 
purchaser causes or permits the Cassette to be serviced or modified by anyone 
other than SYNAPSE SOFTWARE. Any applicable implied warranties, including 
warranties of merchantability and fitness, are hereby limited to 90 days from the 
date of purchase. Consequential or incidental damages resulting from a breach of 
any applicable express or implied warranties are hereby excluded. 


Notice 


All SYNAPSE SOFTWARE computer programs are distributed on an “as is basis 
without warranty of any kind. The entire risk as to the quality and performance of 
such programs is with the purchaser. Should the programs prove defective follow- 
ing their purchase, the purchaser and not the manufacturer, distributor, or retailer 
assumes the entire cost of all necessary servicing or repair. 


SYNAPSE SOFTWARE shall have no liability or responsibility to a purchaser.. 
customer, or any other person or entity with respect to any liability, loss or damage 
caused or alleged to be caused directly or indirectly by computer programs sold 
through SYNAPSE SOFTWARE. This includes but is not limited to any interruption of 
service, loss of business or anticipatory profits or consequential damages resulting 
from the use or operation of such computer programs. 


The provisions of the foregoing warranty are subject to the laws of the state in which 
the Cassette is purchased. Such laws may broaden the warranty protection avail- 
able to the purchaser of the Cassette. 





